Content Type Names

Since transformations occur between named types (i.e. from type A, to type B), it's important to understand how the type names are derived.  The type of the message is determined based on the service contract, which can be WSDL or Java.

For WSDL interfaces, the message name is determined based on the fully-qualified element name of a WSDL message.  Take the following WSDL definition:

<definitions xmlns:tns="urn:switchyard-quickstart:bean-service:1.0">  
  <message name="submitOrder">
    <part name="parameters" element="tns:submitOrder"/>
  </message>
  <portType name="OrderService">
    <operation name="submitOrder">
      <input message="tns:submitOrder"/>
    </operation>
  </portType>
</definitions>

This would yield the following message type name based on the message element name defined in the WSDL:

{urn:switchyard-quickstart:bean-service:1.0}submitOrder

When Java interfaces are used for the service contract, the message name consists of the full package name + the class name, prefixed with "java:".

package org.switchyard.example;
public interface OrderService {
    void submitOrder(Order order);
}

The message type name for the submitOrder method in this Java interface would be "java:org.switchyard.example.Order".  Occasionally, it can be useful to override the default operation name generated for a Java interface.  The @OperationTypes annotation provides this capability by allowing the user to specify the input, output, and/or fault type names used for a Java service interface.  For example, if we wanted to accept XML input content without any need for transformation to a Java object model, the OrderService interface could be changed to look like this:

package org.switchyard.example;
public interface OrderService {
    @OperationTypes(in = "{urn:switchyard-quickstart:bean-service:1.0}submitOrder")
    void submitOrder(String orderXML);
}

Aside from short-circuiting the requirement for transformation, this annotation can be useful if you want to maintain tight control over the names used for message content.

Content Type Names

Since validations occur with named type (i.e. type A) as well as transformations, it's important to understand how the type names are derived.   Please refer to the Content Type Names section in the Transformation chapter if you have not ever seen it.

Property Overriding

SwitchYard property resolver scans the property in following order.

1. System properties and System environment variables

2. Unit test properties

3. JBoss AS7 properties

4. Domain properties

5. SCA composite properties

6. SCA component properties

For example, if you define the property inventory.interface in both of composite and component like this:

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:component name="InventoryService">
        <sca:service name="InventoryService">
            <sca:interface.java interface="${inventory.interface:org.switchyard.quickstarts.demos.orders.InventoryService}"/>
        </sca:service>
        <sca:property name="inventory.interface" value="org.switchyard.quickstarts.demos.orders.InventoryServiceEx"/>
    </sca:component>
    <sca:property name="inventory.interface" value="org.switchyard.quickstarts.demos.orders.InventoryServiceEx2"/>
</sca:composite>

In this case, the composite property "org.switchyard.quickstarts.demos.orders.InventoryServiceEx2" is used as the value of interface attribute. Note that the default value is specified as org.switchyard.quickstarts.demos.orders.InventoryService. You can specify the default property value with "${propertyName:defaultValue}" syntax where "propertyName" is the name of property. If you remove both of composite and component property from above, then the default value is used.

And if you pass a inventory.interface system property like this:

-Dinventory.interface=org.switchyard.quickstarts.demos.orders.InventoryServiceEx3

then the system property overrides all of other properties, so "org.switchyard.quickstarts.demos.orders.InventoryServiceEx3" is used as the value of interface attribute.

In order to set properties to test values, please refer to the "PropertyMixIn Injection" section of the Testing documentation.

Property Escaping

Sometimes, the desired value for a property needs to be in the same "dollar curly" syntax which triggers SwitchYard's property substitution.  This can be problematic because in these cases, you want SwitchYard to leave the configured value alone.  To accomplish this, use a "double dollar curly" syntax instead.  Take the following example:

<foo value="${prop}"/>
<bar value="$${prop}"/>

Assuming the value "prop" is a resolvable property (say, equal to "test"), the value attribute of the foo element will be that value ("test").  However, the value attribute of the bar element will be "${prop}" (with one dollar sign).

Interaction Policy and Implementation Policy

There are two parts to be marked by policies using requires attribute. Interaction Policy is allowed on component service and component reference. Implementation Policy is allowed on component implementation. Each policy belongs to one of these. Implementation Policy is NOT allowed to be marked on component service nor component reference, and Interaction Policy is NOT allowed to be marked on component implementation.

Transaction Interaction Policy

Transaction Interaction Policy is specified using the requires attribute of a component service or component reference definition.

<service name="WorkService" requires="propagatesTransaction">

Valid values for transaction interaction policy are:

• propagatesTransaction - indicates that a global transaction is required when a service is invoked.  If no transaction is present, the SwitchYard runtime will generate an error.

• suspendsTransaction - if a transaction is present, the transaction is suspended before the service implementation is invoked and resumed after the invocation.  This policy setting allows the transactional context of a gateway binding to be separated from the transactional context of the service implementation (e.g. a rollback in the service implementation will not impact the transaction used to receive a message from a JMS queue).

Transaction Implementation Policy

Transaction Implementation Policy is specified using the requires attribute of a component implementation definition.

<implementation.bean class="org.switchyard.quickstarts.demo.policy.transaction.WorkServiceBean" requires="managedTransaction.Global"/>

Valid values for transaction implementation policy are:

• managedTransaction.Global - indicates that this service implementation runs under global transaction.  If no transaction is present, the SwitchYard runtime will create a new JTA transaction before the execution. Created transaction will be committed by SwitchYard runtime at the end of service execution.

• managedTransaction.Local - indicates that this service implementation runs under local transaction containment.  If transaction exists, SwitchYard runtime suspends it. And SwitchYard always create a new JTA transaction before the execution. Created transaction will be committed and suspended transcation will be resumed by SwitchYard runtime after the invocation. Note that since the local transaction containment doesn't propagate its transaction through the reference, all of the component reference must be marked as suspendsTransaction. If not, SwitchYard will generate an error.

• noManagedTransaction - indicates that this service implementation runs under no managed transaction.  If transaction exists, SwitchYard runtime suspends it before the service implementation is invoked and resumed after the invocation.

Setting Transaction Policy

Transaction policy can be specified by editing the SwitchYard application descriptor (switchyard.xml) and adding the requires attribute to a service/reference definition.  Another option is to use the @Requires attribute in your service implementation to declare service interaction and implementation policy for the service.  When the application project is built, SwitchYard will discover @Requires annotations and automatically generated the required configuration.

@Service(WorkService.class)
@Requires(transaction = {TransactionPolicy.PROPAGATES_TRANSACTION,TransactionPolicy.MANAGED_TRANSACTION_GLOBAL})
public class WorkServiceBean
    implements org.switchyard.quickstarts.demo.policy.transaction.WorkService {
}

And @Requires annotations could be used to declare reference interaction policy as well.

@Inject @Reference @Requires(transaction = TransactionPolicy.PROPAGATES_TRANSACTION)
private TaskAService _taskAService;

Scope of Support

Support for transaction policy is limited to bean services (implementation.bean), bpm services (implementation.bpm), JCA inflow in the JCA Gateway (binding.jca) and JMS endpoints in the Camel gateway (binding.camel).  Support for other implementation types and gateways will be added in the future.

Setting Security Policy

Security policy can be specified by editing the SwitchYard application descriptor (switchyard.xml) and adding the requires attribute to a service definition.  Another option is to use the @Requires attribute in your service implementation to declare security policy for the service.  When the application project is built, SwitchYard will discover @Requires annotations and automatically generated the required configuration.

@Service(WorkService.class)
@Requires(security = {SecurityPolicy.AUTHORIZATION, SecurityPolicy.CLIENT_AUTHENTICATION, SecurityPolicy.CONFIDENTIALITY})
public class WorkServiceBean
    implements org.switchyard.quickstarts.demo.policy.security.WorkService {
}

Security Processing

When the container does not automatically provide certain security policies, SwitchYard can be configured to process security credentials extracted from the binding-specific data, then provide certain security policies itself (like clientAuthentication).  See the Security section of the documentation for details.

Scope of Support

Support for security policy is limited to bean services (implementation.bean), SOAP endpoints via the SOAP gateway (binding.soap), and HTTP endpoints via the HTTP gateway (binding.http).  Support for other implementation types and gateways will be added in the future.

The <component><service> and <component><reference> security Attribute

Component Services and Component References can specify an optional sy:security attribute (namespace prefix required, as the SCA schema is being extended).  This attribute points to a named <security> element in the domain section.  If not defined, default will be inferred.

The <securities> Element

This is an optional element.  Contains any number of <security> elements.  If not defined, a default security configuration is still used.  See the <security> element below.

The <security> Element

This is an optional element.  If not specified, the callbackHandler, name, and securityDomain attributes described below will fallback to their default values.

The callbackHandler Attribute

This is an optional attribute.  If not specified, a default value of org.switchyard.security.callback.NamePasswordCallbackHandler will be used.  See the Callback Handlers section below for details on CallbackHandlers.

The name Attribute

This is an optional attribute.  If not specified, a default value of default will be used.  Component Services and Component References point to this name.

The rolesAllowed Attribute

This is an optional attribute. If specified, and if a Service has an authorization security policy requirement, the authenticated user must be in one of the roles listed. The value is a comma-separated list of roles (whitespace gets trimmed).

The runAs Attribute

This is an optional attribute. If specified, the value of this attribute will be added as a role to the authenticated user.

The securityDomain Attribute

This is an optional attribute.  If not specified, a default value of other will be used.  The value maps to a JAAS security domain name.  See the Login Modules section below for details on LoginModules.

The <properties> and <property> Elements

A <security> element can optionally specify a <properties> element, which can optionally specify zero to many (0..*) <property> elements.  Each <property> element has two required attributes: name and value.

The list of specified name/value properties are made available to the SwitchYard Security configuration, as well as the configured callbackHandler.  Some CallbackHandlers require configuration information beyond what can be assumed in a no-argument constructor.  See the individual CallbackHandler implementations for details.

NamePasswordCallbackHandler

Provides name and password credentials to a configured LoginModule stack.  For example, the UsersRoles LoginModule that comes out-of-the-box in JBoss AS7.

STSTokenCallbackHandler

Provides assertion credentials to a configured LoginModule stack.  For example, the PicketLink STSValidatingLoginModule that comes out-of-the-box in JBoss AS7.

STSIssueCallbackHandler

Wraps both the NamePasswordCallbackHandler and the STSTokenCallbackHandler, so as to provide name, password and assertion credentials to a configured LoginModule stack.  For example the UsersRoles LoginModule and STSIssuingLoginModule that comes out-of-the-box in JBoss AS7.

CertificateCallbackHandler

Provides Certificate credentials to a configured LoginModule stack.  SwitchYard 0.7+ provides a CertificateLoginModule for this purpose.

Installation

Please refer to Installing Eclipse Tooling for details on installing the SwitchYard Eclipse tooling.

Features

The SwitchYard Eclipse tooling provides the following features:

• Creation of SwitchYard projects.

• Adding SwitchYard capabilities to existing Maven based Eclipse projects.

• Configuration of SwitchYard capabilities (i.e. runtime component dependencies; e.g. SOAP, BPM, Camel, etc.).

• A graphical editor for editing SwitchYard application configuration (i.e. switchyard.xml), which provides the following features:

  • Creation and configuration of components, services and references.

  • Component service/reference promotion and configuration of gateway bindings.

  • Creation of implementation skeletons for new service components (e.g. bean classes, BPMN2 files, DRL files, etc.).

  • Creation of unit test skeletons for services.

  • Configuration of message transformers, including creation of implementation skeletons for message transformers (e.g. XSL, Java, etc.).

  • Creation of Artifact references.

• Java2WSDL

• XML catalog entries for SwitchYard configuration schema.

• m2eclipse integration supporting the SwitchYard Maven plugin (org.switchyard:switchyard-plugin).

• Support for workspace deployment of SwitchYard projects.

Overview

This quickstart takes you through the steps required to create, implement, test and deploy a SwitchYard application using the Eclipse tooling.  The application being created will provide a greeter service, implemented as a Java bean and accessible via a SOAP HTTP gateway.  This quickstart will illustrate how to perform the following tasks:

• Create a SwitchYard project

• Create a Java service interface

• Create a bean component implementation

• Create and execute a unit test for the service

• Create a WSDL service interface

• Add a SOAP gateway for accessing the service

• Create a transformer

• Create and execute a unit test for the transformer

• Create and execute a unit test for the SOAP gateway

• Deploy the application to a server

• Test the deployed application

Create a Project

The first step is to create a project for the application.  From the new menu, select SwitchYard Project.  (See SwitchYard Projects for more details.)

The first page in the wizard is used for specifying the project name and location.

The next page is used for specifying various project details, including which SwitchYard components are required by the project.  In this example, the default package has been modified and the Bean and SOAP components have been selected.

Upon completion, a new project will be created and the SwitchYard configuration will be open in the editor.

Create a Bean Component

The next step is to create a component that will implement the service logic.  Every component must be associated with an interface describing the service.  As part of this step, we will create the interface using the Interface link on the New Bean Service wizard.  At the end of this step, we will have:

• A new ExampleService.java file describing a Java interface that will be implemented by the component.  This will provide the interface for the service.

• A new ExampleServiceBean.java file describing a Java class that implements ExampleService.  This will provide the implementation for the service.

• A component and component service will be added to the SwitchYard configuration.  This tells SwitchYard about the service and implementation.

In the SwitchYard editor, drag the Bean tool from the Components section of the palette onto the canvas.  This will open a wizard prompting for details about the component.

First, specify the service interface.  Create a new interface by clicking the Interface link.  This will open the standard Java New Interface wizard.  Specify a name for the interface (e.g. ExampleService), any other details and press Finish.

The name for the bean should be defaulted based on the service name (e.g. ExampleServiceBean).  Look over the fields and press Finish.

A new component shape should be added to the canvas.

Save the changes to the switchyard.xml file.

Flesh Out the Service Interface

The next step is to flesh out the interface for the service.  The Java interface created in the previous step contains no methods, so we will add them here.  At the end of this step, we will have a complete interface which describes the service.

In the SwitchYard editor, double-click the service icon on the component (the green arrow on the left side of the component).  This will open the file describing the interface (ExampleService.java).

Add a method to the interface, for example:

package com.example.switchyard.example;

public interface ExampleService {

	public String sayHello(String name);

}

Implement the Bean

The next step is to implement the service logic.  After adding methods to the interface in the previous step, there are compiler errors in the bean class.  We will resolve the errors by creating the missing methods.  At the end of this step we will have a completed service implementation and will have a SwitchYard application that provides an ExampleService and the project should be error free.

In the SwitchYard editor, double-click the component (ExampleServiceBean) in the diagram.  This will open the file used to implement the component (ExampleServiceBean.java).

The file should contain errors, since it does not implement required methods.

Add an implementation for the newly added method on the service interface.  (Using quick-fix, click the error icon and select, Add unimplemented methods.)

Update the implementation of the sayHello() method so it matches the following:

package com.example.switchyard.example;

import org.switchyard.component.bean.Service;

@Service(ExampleService.class)
public class ExampleServiceBean implements ExampleService {

	@Override
	public String sayHello(String name) {
		return "Hello, " + name;
	}

}

Create a Unit Test for the Service

The next step is to verify that the service implemented in the previous steps is behaving appropriately.  To do that, we will create a unit test to verify the behavior.  At the end of this step we will have a unit test class which sends a message to the service and verifies its output.  We will also execute the test using the native Eclipse JUnit support.

In the SwitchYard editor, right-click the service icon on the component (the green arrow on the left side of the component) and select New Service Test Class.  This will open a wizard, which should be defaulted appropriately.  Look the fields over and press Finish.

Modify the testSayHello() method to properly exercise the service.  Initialize the message variable to "Bob" and update the Assert statement to verify the return value from the service is, "Hello, Bob"

package com.example.switchyard.example;

import org.junit.Assert;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.switchyard.test.Invoker;
import org.switchyard.test.ServiceOperation;
import org.switchyard.test.SwitchYardRunner;
import org.switchyard.test.SwitchYardTestCaseConfig;
import org.switchyard.test.mixins.CDIMixIn;

@RunWith(SwitchYardRunner.class)
@SwitchYardTestCaseConfig(mixins = CDIMixIn.class, config = SwitchYardTestCaseConfig.SWITCHYARD_XML)
public class ExampleServiceTest {

	@ServiceOperation("ExampleService")
	private Invoker service;

	@Test
	public void testSayHello() throws Exception {
		// initialize your test message
		Object message = "Bob";
		String result = service.operation("sayHello").sendInOut(message)
				.getContent(String.class);

		// validate the results
		Assert.assertTrue("Unexpected result: " + result, result.equals("Hello, Bob"));
	}

}

Run the tests by selecting Run As => JUnit Test.

Promote the Service

The next step is to configure the service so it can be invoked by external applications.  This is process is called promotion.  We will promote our service through a WSDL interface which will require the creation of a WSDL file to describe the external version of the service, as well as the creation of a couple of transformers to convert the between the different types exposed by the internal and external interfaces (i.e. between the Java and WSDL types).  The SwitchYard tooling allows us to create the WSDL and the required transformers during the promotion process.

In the SwitchYard editor, right-click the service icon on the component and select Promote Component Service.  This will open a wizard, which allows us to specify the interface that will be exposed by the promoted service.  By default, the interface specified matches the interface used to describe the component service.

In the Promote Component Service wizard, change the interface type from Java to WSDL.  This will blank out the interface and name fields.

To create the WSDL, from the Java interface describing the source, press the Interface link.  This will open the Java2WSDL wizard.

The first page of the Java2WSDL wizard is used for specifying the name and location for the WSDL file.  The default values should be appropriate.  Look them over and press Next.

The next page is used for specifying details about the generated WSDL.  The default values should be appropriate, but you may want to modify the Endpoint URI field.  Look the values over and press Finish.

The WSDL file is created and we should be back on the Promote Component Service wizard, which should now be defaulted with details from the newly created WSDL file.  Notice that the Create required transformers button is checked and press Next.

The next page is the New Transformers page which allows us to create the required transformers.  Notice the two transformer type pairs checked in the table correspond to the input and output types declared on the two interfaces.  Ensure both pairs are checked and Java Transformer is selected as the Transformer Type and press Next.

The next page collects information for a new Java class that will be used to implement the transformers.  Specify ExampleServiceTransformers for the name and leave org.w3c.dom.Element selected as the Java type to be used to represent XML/ESB types in the transformer class.  Press Finish.

A new composite service promoting the component service should have been added to the SwitchYard configuration.  Save the editor.

In addition, there should be a new ExampleServiceTransformers.java file in the workspace.

Select the main shape in the SwitchYard editor and review the contents of the Transforms tab in the Properties view.  The newly added transformers should be listed.

	@Test
	public void testSayHelloTransform() throws Exception {
		final QName inputType = QName
				.valueOf("{urn:com.example.switchyard:switchyard-example:1.0}sayHello");
		final QName outputType = QName
				.valueOf("{urn:com.example.switchyard:switchyard-example:1.0}sayHelloResponse");
		// initialize your test message
		Object message = "<sayHello xmlns=\"urn:com.example.switchyard:switchyard-example:1.0\"><string>Bob</string></sayHello>";
		String result = service.operation("sayHello").inputType(inputType)
				.expectedOutputType(outputType).sendInOut(message)
				.getContent(String.class);

		// validate the results
		String control = "<sayHelloResponse xmlns=\"urn:com.example.switchyard:switchyard-example:1.0\"><string>Hello, Bob</string></sayHelloResponse>";
		Assert.assertTrue("Unexpected result: " + result,
				XMLUnit.compareXML(control, result).identical());
	}

	@Transformer(to = "{urn:com.example.switchyard:switchyard-example:1.0}sayHelloResponse")
	public static String transformStringToSayHelloResponse(String from) {
		// TODO: properly escape the input string
		return "<sayHelloResponse xmlns=\"urn:com.example.switchyard:switchyard-example:1.0\"><string>"
				+ from + "</string></sayHelloResponse>";
	}

	@Transformer(from = "{urn:com.example.switchyard:switchyard-example:1.0}sayHello")
	public String transformSayHelloToString(Element from) {
		return from.getTextContent();
	}

Test the Deployed Service

With our application deployed, our service is now available to SOAP HTTP clients.  To verify, we will use the web services tester that ships with Eclipse, but you could use the web services test/debug tool you are most familiar with.

Right-click the WSDL file (ExampleService.wsdl) and select Web Services→Test with Web Services Explorer.  Exercise the service using the tester

View Details in the Management Console

Right-click the server in the Servers view and select Show In→Web Management Console.  Refer to the SwitchYard management console documentation for details.

Creating a New SwitchYard Project

The tooling provides a new project wizard which creates a new Maven project in your workspace.  The new project contains the following:

• pom.xml file containing dependencies and build plugin configuration for the selected SwitchYard components.

• src/main/resources/META-INF/switchyard.xml file, initialized using information from the wizard.

• beans.xml file in src/main/resources/META-INF/ and src/test/resources/META-INF/ (required to support CDI)

• folder hierarchy in src/main/java and src/test/java for the default Java package

Upon completion of the wizard, the project will be created and the project's switchyard.xml file will be opened in the SwitchYard editor.

To create a new SwitchYard project, select SwitchYard Project from the SwitchYard category the File→New→Project... wizard.

The first page is a basic new project screen, allowing the user to specify the name and location of the new project:

The second page allows the user to specify some basic project details, including:

• The Maven groupId for the project.

• The target namespace for the SwitchYard application.

• The default Java package name for the project.

• The SwitchYard runtime version.

• The SwitchYard runtime components (e.g. BPM, Camel, SOAP, etc. support) required for the project.

Press Finish to create the new project.

Configuring SwitchYard Capabilities on Existing Projects

SwitchYard capabilities may be added to any existing Maven project in the workspace.  To add/modify SwitchYard capabilities, simply right-click the project and select, Configure -> SwitchYard Capabilities... A prompt will be displayed asking for confirmation.

A property dialog will be displayed, allowing configuration of the SwitchYard runtime required by the project.

Any changes made will be reflected in the project's pom.xml file (e.g. dependencies, build plugin configuration, SwitchYard version).Unit Testing

The SwitchYard tooling provides support for stubbing out test classes for services.

@RunWith(SwitchYardRunner.class)
@SwitchYardTestCaseConfig(mixins = CDIMixIn.class, config = SwitchYardTestCaseConfig.SWITCHYARD_XML)
public class SomeServiceTest {

    @ServiceOperation("ExampleService")
    private Invoker service;

    @Test
    public void testSomeInOnlyOperation() throws Exception {
        // TODO Auto-generated method stub
        // initialize your test message
        Object message = null;
        service.operation("someInOnlyOperation").sendInOnly(message);

        // validate the results
        Assert.assertTrue("Implement me", false);
    }

    @Test
    public void testSomeInOutOperation() throws Exception {
        // TODO Auto-generated method stub
        // initialize your test message
        Object message = null;
        String result = service.operation("someInOutOperation")
                .sendInOut(message).getContent(String.class);

        // validate the results
        Assert.assertTrue("Implement me", false);
    }

}

Workspace Deployment

SwitchYard projects created through the new wizard are created as faceted projects, configured as Utility Modules.  This allows the user to mark the project for deployment to a JEE server.

Creating a Project

The first thing you'll want to do with Forge is create a new project.  This can be done inside the Forge shell using the new-project command.

switchyard$ forge
    _____                    
   |  ___|__  _ __ __ _  ___ 
   | |_ / _ \| `__/ _` |/ _ \  \\
   |  _| (_) | | | (_| |  __/  //
   |_|  \___/|_|  \__, |\___| 
                   |___/      
 
[no project] switchyard $ new-project --named syApp --topLevelPackage org.switchyard.examples.forge
 ? Use [/private/tmp/switchyard/syApp] as project directory? [Y/n] 
***SUCCESS*** Created project [syApp] in new working directory [/private/tmp/switchyard/syApp]

At this point, you have an empty application with a few Maven facets installed.  What's a facet you ask?  Read on ....

Facets

Facets add capabilities to an application and to the forge environment itself.  This allows SwitchYard to add dependencies to your application's pom based on the functionality you will be using, instead of sticking every possible SwitchYard dependency in the application by default.  Facets are also used to add commands specific to SwitchYard itself and components which you will be using in your application.  The following facets are currently available:

• switchyard - core set of commands and dependencies for the SwitchYard runtime

• switchyard.bean - commands and dependencies for Bean component services

• switchyard.bpm - commands and dependencies for BPM component services

• switchyard.rules - commands and dependencies for Rules component services

• switchyard.soap - commands and dependencies for SOAP gateway bindings

• switchyard.camel - commands and dependencies for Camel services and gateway bindings

• switchyard.rest - commands and dependencies for RESTEasy gateway bindings

• switchyard.http - commands and dependencies for HTTP gateway bindings

Installing a facet can be done directly in the shell using the install-facet command.

[syapp] syapp $ project install-facet switchyard.soap
***SUCCESS*** Installed [switchyard.soap] successfully.
Wrote /tmp/syapp/pom.xml

Commands

The following SwitchYard commands are available in Forge (grouped by facet).

switchyard

• switchyard show-config : displays the current state of your application's configuration, including services, references, and bindings.

• switchyard promote-service : promotes an internal application-scoped service to be visible to other applications.

• switchyard promote-reference : promotes an internal application-scoped reference so that it can be mapped to services provided in other applications.

• switchyard create-service-test : create a new unit test for a service.

• switchyard get-version : returns the version of SwitchYard used by the application.

• switchyard trace-messages : enables message tracing at runtime - all messages will be logged.

• switchyard import-artifacts : add a dependency on a service artifact module to the application's configuration

• switchyard add-reference : adds a reference to a service implementation; particularly useful for service types which do not autogenerate references (Camel, BPM, BPEL).

switchyard.bean

• bean-service create : creates a new CDI Bean service, consisting of a service interface and implementation class.

switchyard.bpm

• bpm-service create : creates a new BPM service, consisting of a service interface and implementation class.

switchyard.rules

• rules-service create : creates a new Rules service, consisting of a service interface and implementation class.

switchyard.camel

• camel-service create : creates a new XML or Java DSL Camel route.

• camel-binding bind-service : binds a service using a Camel endpoint URI.

• camel-binding bind-reference : binds a reference using a Camel endpoint URI.

switchyard.soap

• soap-binding bind-service : binds a service to a SOAP endpoint.

• soap-binding bind-reference : binds a reference to a SOAP endpoint.

switchyard.rest

• rest-binding bind-service : binds a service to a RESTEasy endpoint.

• rest-binding bind-reference : binds a reference to a RESTEasy endpoint.

switchyard.http

• http-binding bind-service : binds a service to a HTTP endpoint.

• http-binding bind-reference : binds a reference to a HTTP endpoint.

Overview

The SwitchYard management console is integrated with the standard JBoss AS management console and provides the following:

• A view of the applications and services deployed on the server.

• A view of various execution metrics.

• A view of the SwitchYard subsystem configuration.

SwitchYard contributes views to the standard JBoss AS management console's Runtime and Profile pages.

Metrics Views

SwitchYard Message Metrics can be accessed on the Runtime page of the AS console under Status -> Subsystems -> SwitchYard.  This page provides a view of a comprehensive set of metrics aggregated at various levels within the system.

The following types of metrics are available:

• Message count: total, success, failed

• Processing time: total, min., avg., max.

Collected metrics can be viewed at the following levels:

• System : metrics for the entire SwitchYard runtime (all deployed applications)

• Service : metrics for a composite service in an application. Additional metric details are provided for the following:

  • Gateway: metrics for each binding on the service (e.g. FTP metrics for service "ABC")

  • Operation: metrics for each operation on the service

  • Service Reference : metrics for references invoked by the service

• Reference : metrics for a composite reference in an application.  Additional metric details are provided for the following

  • Gateway : metrics for each binding on the reference (e.g. FTP metrics for reference "ABC")

  • Operation : metrics for each operation on the reference

This page also provides the user with the ability to reset metrics at various levels.

Application Views

SwitchYard contributes a page to the Runtime Operations section which provides views detailing various aspects of SwitchYard applications running on the system.  These views may be accessed on the Runtime page of the AS console by selecting Runtime Operations -> SwitchYard.  The following views are provided:

• Applications: lists all SwitchYard applications deployed on the server

• Services: lists all Services provided by the applications deployed on the server

• References: lists all service References used by applications deployed on the server

• Artifacts: lists all artifacts referenced by applications deployed on the server

Subsystem Configuration View

SwitchYard contributes an additional view to the standard JBoss AS management console's Profile page, which can be accessed by selecting the Subsystems -> SwitchYard -> Runtime Details node.  This page displays details about to the SwitchYard subsystem configured in the AS configuration profile.

This page displays the version of the SwitchYard runtime, along with a list of installed components.  Selecting a component will populate the Component Details section below, which displays:

• Name: the component name, e.g. SOAP, Camel.

• Type: the component type, e.g. soap, camel.  (The type is the suffix used within switchyard.xml identifying component specific elements, e.g. binding.soap, implementation.camel.)

• A section providing component specific details.  For most components, this section lists any configurable properties and their current settings.